The C toolchain manager
~~~~~~~~~~~~~~~~~~~~~~~
This tool is meant for setting up per-project toolchains, comprising
of compiler, linker etc, some headers and linkable libraries.

    mkdir /var/tool/project1
    cd /var/tool/project1

    ctool use arm-gcc-9.3
    ctool add musl
    ctool add libcurl

The project can then be configured to use

    CC=/var/tool/project1/bin/cc
    LD=/var/tool/project1/bin/ld
    ...

Both cc and ld above are scripts calling the real cc and ld, wherever those
are installed, and passing them options to use the libraries from
/var/tool/project1:

    #!/bin/sh

    exec /opt/arm-gcc-10.1/gcc \
            -B /var/tool/project1/bin \
	    -I /var/tool/project1/inc \
	    -L /var/tool/project1/lib \
	    "$@"

Once the project is done, the toolchain directory gets removed whole since
it only contains the "working copy" of the toolchain.


No system compiler
~~~~~~~~~~~~~~~~~~
The approach taken here is quite different from what is commonly expected
in a GNU system. The idea here is to remove the concept of a "system compiler"
and effectively build everything with cross-compilers, including the code built
to run locally.


Host/target separation
~~~~~~~~~~~~~~~~~~~~~~
By design, ctool the host and the target parts of the toolchain differently.

The host parts are the tools that run on the host: compiler, linker, assembler
and whatever else the project might need. The tools are managed by the system
package manager, just like any other executables on the host.
ctool itself doesn't do anything about the host tools, only references them.

The target parts of the toolchain are the headers and the linkable libraries
which describe the target system for the compiler. These are the parts that
ctool manages, in the sense of package management.

The intended workflow for a project targeting an ARM Linux system is to

    * install an ARM compiler on the host using the system package manager
    * use ctool to pair that compiler with libraries for the target system

This approach is a bit at odds with the GNU wordview, and might require some
extra care when dealing with e.g. GCC private libraries.


Library packs
~~~~~~~~~~~~~
Pre-built libraries are packed into PAC archives (see ../mpac) with two
top-level directories, "inc" and "lib", containing headers and linkable
libraries respectively.

    inc/foo.h
    inc/foo/some.h
    inc/foo/other.h
    lib/libfoo.a
    (or lib/libfoo.so)

These files get unpacked right into the toolchain directory, with only some
basic checks to avoid overwriting existing files.


Toolchain description
~~~~~~~~~~~~~~~~~~~~~
The `use` subcommand reads a simple text file describing the contents of the
bin/ directory.

    bin/as      # symlink to /opt/arm-binutils/as
    bin/readelf # symlink to /opt/arm-binutils/readelf
    bin/ld      # script calling /opt/arm-bintuils/ld with the right -T option
    bin/gcc     # script exec'ing /opt/arm-gcc-9.3/gcc with the right -B, -L,
                # -I and -specs options referencing the toolchain directory
    musl.specs  # the specs file, also referencing the toolchain directory

Unlike with library packs, the scripts in bin/ are host-dependent more than
they are target-dependent, and in most cases must reference the toolchain
directory itself (to let the compiler know where to look for headers etc).

Simple text substitution is used to handle toolchain directory references in
in scripts and specs.

See ../../etc/tool/ for some examples.
